Computer Associates ERwin 4.0 ReadmeAPI.txt File

Date Last Updated: July 19, 2001

Copyright (c) 2001. Computer Associates International, Inc.
All rights reserved.

This ReadmeAPI.txt file presents information specific to the ERwin API features provided in ERwin 4.0 - Service Pack 1.

When you open this file in Microsoft Notepad, be sure to turn on the Word Wrap, which is located on the Edit menu.

* How to Print This File
To print this Readme file, open it in Notepad or another word processor, then choose Print on the File menu.
-----------------------------------------------------------
Contents
-----------------------------------------------------------

1. API Changes/Enhancements
2. ERwin Metamodel Changes/Enhancements
3. Sample Applications
4. Contacting Technical Support

------------------------------------------------------------
1. API Changes/Enhancements
------------------------------------------------------------
Documentation for the ERwin API is provided in the Doc directory in the file ERwin ScriptClientApi.pdf. The ERwin API has been modified to include the following:

* Support for Non-unique Persistence Unit Ids

In the API, all Persistence Units are identified by a unique ID. The Id is available via ISCPersistenceUnit::ObjectId property and can be used with Persistence Unit collection to identify a unit. For instance, ISCPersistenceUnitCollection::Remove the first parameter can accept a unit ID in order to specify which unit should be removed from the collection.

When a model is saved using SaveAs, the model retains its original Id. Therefore, if both the original model and the SaveAs model are opened in ERwin at the same time, two Persistence Units in the Persistence Unit collection will have the same Id. In this case, if an Id is used for Item, Remove, Delete calls to Persistence Unit collection, the API will use the first unit from the sequence of units with duplicate ids in the collection. To uniquely address a Persistence Unit, a position index in the collection should be used. Another way to uniquely identify a Persistence Unit is to use an instance of ISCPersistenceUnit interface.

* Option to Hide/Show Persistence Unit (model) in ERwin UI

The functionality is only available when the ERwin UI is present and does not apply for the 'stand-alone' mode. The show/hide option for a model involves setting/retrieving a value for the Hidden Model property via ISCPropertyBag interface. When Persistence Bag is requested from Persistence Unit, the property will be set to false when a model associated with the persistence unit is not visible. The property will be set to true if the model is visible in the ERwin UI.

A model can be rendered not visible, by setting the property to false in a Property Bag, and submitting the Property Bag to the API via the ISCPersistenceUnit interface. By default, a new Persistence Unit, created via method ISCPersistneceUnitCollection::Create, is hidden. A Persistence Unit loaded via ISCPersistenceUnitCollection::Add is shown by default in the ERwin UI.

* Default Value for MustBeOff on Property Flags 

To ensure backward compatibility with the previous versions of the API, the default values is set to SCD_MPF_NULL for the methods:

 ISCModelObject::CollectProperties
 ISCModelPropertyCollection::HasProperty 

With MustBeOff for model object properties set to SCD_MPF_NULL, only properties with values are reported in a collection.

* Method Fixed

The behavior of ISCModelPropertyCollection::Item method has been fixed and has been made more consistent. 

Before the fix, the result of Item (GetItem) calls were varied, and depended on the context of the call. If the call was made with a transaction active (Session::BeginTransaction), then the call returned a point to ISCModelProperty. However, if there was no active transaction at this point, then the call would return the pointer only if a property had a value for the model object. In all other cases, the call would fail. In the case of ReadOnly/Tool Maintained properties, if the property did not have a value, regardless of the status of a transaction, the call to Item method would fail as well.

In this release, this inconsistency in behavior is resolved, and Item will now always return the not NULL pointer to the ISCModelProperty interface. The only requirement is that the property be legal for this class of model objects. The valid pointer is returned regardless of the fact that the property does or does not have a value for an instance of a model object.

This fix allows you to check the property datatype and flags regardless if the property has a value and regardless of session transaction status. However, an attempt to retrieve a value will fail if the property does not have a value. A call to set a new value for ReadOnly/Tool Maintained properties will also fail.

With the introduction of this fix, the correct sequences to check on the existence of a value for a model property are:

* Use the HasProperty method of ISCModelPropertyCollection. The method returns true only if a property has a value. The behavior of the method has not changed from the previous releases.

* Use Item method, receive ISCModelProperty pointer, check on Flags values for the property. If the property does not have a value, the NULL value flag (SCD_MPF_NULL) will be set to one. Alternatively, you can try to retrieve a value. If the value is not present, the API will return an error code. In previous releases, an Item call returned an error if the property did not have a value and there was no active transaction.

------------------------------------------------------------
2. ERwin Metamodel Changes/Enhancements
------------------------------------------------------------

The property type for "Target of Transform" has been changed from scalar to vector. The following classes of objects can have instances of the property: Entity, Attribute, Relationship.

This property holds values that are references to the participating transforms. There could be cases, specifically for relationships, when more than one transform is supervising the object. This change has been made to support models in which transforms are nested.

------------------------------------------------------------
3. Sample Applications
------------------------------------------------------------
* ERwin Spy

The ERwin 4.0 installation offers two extra items: a sample of the ERwin API client program and the ERwin Spy utility. These items are located in Samples\ERwin API subdirectory off the ERwin installation directory.

-- ERwin API Sample Client
Located in Samples\ERwin API\Sample Client subdirectory, the sample client consists of two Visual Basic 6.0 projects: ERwinSpy_Sample.vbp and ErwinSpy_Addin_Sample.vbp, which are stand-alone and add-in versions of a sample program, respectively.

a) The stand-alone version, when built, creates the ERwinSpy_Sample.exe program. This program is an ERwin model data browser that you can use to research ERwin data internals, such as the ERwin metamodel, ERwin model data, and model objects and their properties. 

Using the browser, you can open an ER1 file, by choosing Open from the File menu. When a model is opened or selected from Model menu, model 
objects from the model are displayed in the left pane. You can view a model object's hierarchy (parents and children) by double-clicking on the object. You can view the properties of an object by clicking the button between left and right panes in the center of the program screen.

The Modules menu shows in-memory models that are currently open. The upper part of the menu can be used to access model data and the lower part is used to access to metamodel information associated with the model.

b) The add-in version is similar to stand-alone one, except it runs from ERwin Tools/Add-Ins menu. In order to use the add-in version:

- an add-in component should be built by using ErwinSpy_Addin_Sample.vbp project.

- the component should be registered with ERwin via Tools/Add-ins/Customize menu. In the Add-in manager dialog box that opens by using the menu, choose to add a new item (Add Menu Item button from the toolbar in the middle of the dialog). In the Menu Item Details area of the dialog, set Name to AddIn Sample; COM ProgId to ERwinSpy_AddIn_Sample.ErwinSpy and Function Name to Run. Select the Com Object in Menu Type area of the dialog for these settings to be correct. Click the Save button to save.

When the after sequence is executed, a new menu item will be created in the ERwin Tool menu under Add-Ins. The name of the item matches the text that was typed in Name field of customization dialog (e.g., AddIn Sample in this case). You can select this new menu item to activate the add-in sample component. The Models menu of the add-in shows models opened in ERwin.

* ERwin Spy Utility

The utility is an improved version of the sample described above. Located in Samples\ERwin API\ERwin Spy subdirectory, the utility consists of two programs: ERwinSpy.exe and ErwinSpy_Addin.dll, which are stand-alone and add-in versions, respectively. The directory has also a help file to provide information about the ERwin Spy Utility.

To register the ERwin Spy component with ERwin, first register the add-in component with the system registry: 

regsvr32.exe <ERwin installation directory\Samples\ERwin API\ERwin Spy>ErwinSpy_Addin.dll

To register the add-in with ERwin, on the Tools menu in ERwin, choose Add-Ins, then choose Customize. In the Add-In Manager dialog, click the Add Menu Item button from the toolbar. In the Add New Menu Item dialog, set Name to Erwin Spy, set COM ProgId to ERwinSpy_AddIn.ErwinSpy, and set Function Name to Run. Note that in the Menu Type box on the dialog, you should select Command and Com Object.

------------------------------------------------------------
4. Contacting Computer Associates Technical Support
------------------------------------------------------------

If you need technical support, you can visit the Computer Associates Technical Support web site at http://esupport.ca.com. 

* For online support, select "Star TCC" from the "Support Resources" list. 

* For telephone support, select "Calling CA for Support" from the "Support Services" list and find the telephone number for your calling area.

When you contact Computer Associates Technical Support, please have the following information ready for the support analyst:

* The version number and the build number of the product (available from the About menu option on the Help menu).

* The operating system or platform (for example, Windows NT 4.0), as well as any service pack applied.

* A description of the problem, the steps that led to the problem, and any error messages.

Thank you for using Computer Associates products. 
